Document the design in package-info (client-side stats) by dougqh · Pull Request #12082 · DataDog/dd-trace-java

dougqh · 2026-07-27T16:36:31Z

What Does This Do

Adds a package-info.java for datadog.trace.common.metrics — a two-minute mental model of the re-architected client-side-stats (CSS) pipeline for newcomers to the package.

Documentation only; no production code changes.

Motivation

Document the new architecture of client-side stats -- including thread safety, config update model, and publishing cycle

Additional Notes

At-a-glance ASCII flow diagram — producer threads → MPSC inbox → single aggregator thread (canonicalize → fold → flush).
Threading model — the load-bearing single-writer invariant (aggregator thread owns all mutable state; cross-thread mutations funnel through the inbox).
The cycle — per-interval aggregate then flush via MetricWriter (msgpack / OTLP); buckets are deltas.
Cardinality invariant — bound distinct values per tag → collapse overflow into a sentinel → report collapses per cycle, so the bounding is observable without becoming unbounded itself.
The three handler families — CoreHandlers / PeerTagSchema / AdditionalTagsSchema.

The per-class javadocs already carry the mechanics; this is deliberately the top-level shape, not a reference — kept to a short prose read per reviewer feedback that an earlier exhaustive draft was too dense.

Stacking

Stacked on #11402 (the CSS re-architecture this documents). Rebase --onto master once #11402 squash-merges.

🤖 Generated with Claude Code

datadog-datadog-prod-us1-2 · 2026-07-27T16:52:25Z

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 57.68% (-0.03%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: f720209 | Docs | Datadog PR Page | Give us feedback!}

datadog-datadog-prod-us1-2

More details

The PR adds only package-level Javadoc; it introduces no runtime path or behavioral change. The documented CSS invariants match the surrounding aggregator, schema, and writer implementation, and deterministic diff/link checks passed; Gradle compile, test, and Javadoc tasks could not run because the sandbox lacks network access to the wrapper distribution and Java 25 toolchain.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit 50cecf3 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50cecf306a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Add a package-info.java for datadog.trace.common.metrics giving a two-minute mental model of the re-architected client-side-stats (CSS) pipeline: an at-a-glance ASCII flow diagram plus prose on the single-writer threading model, the per-interval aggregate/flush cycle, the bound->sentinel->report-per-cycle cardinality invariant, and the three cardinality-handler families. The per-class javadocs carry the mechanics; this is the top-level shape for a newcomer. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

dd-octo-sts · 2026-07-28T13:48:03Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.02 s	13.99 s	[-0.7%; +1.1%] (no difference)
startup:insecure-bank:tracing:Agent	12.88 s	12.99 s	[-1.5%; -0.3%] (maybe better)
startup:petclinic:appsec:Agent	16.79 s	16.09 s	[-0.0%; +8.8%] (no difference)
startup:petclinic:iast:Agent	16.44 s	16.89 s	[-6.9%; +1.6%] (no difference)
startup:petclinic:profiling:Agent	16.69 s	16.80 s	[-1.9%; +0.6%] (no difference)
startup:petclinic:sca:Agent	16.84 s	16.33 s	[-1.4%; +7.6%] (no difference)
startup:petclinic:tracing:Agent	16.10 s	15.91 s	[+0.2%; +2.2%] (maybe worse)

Commit: f720209d · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

- report() resets entries (retained for reuse; stale expunged over cycles), it does not clear the whole table each interval - OTLP flushes to the OTLP endpoint, not the agent; only msgpack goes to the agent - core string fields use PropertyCardinalityHandler, peer/additional tags use TagCardinalityHandler; primitive key fields are copied directly Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Adopt bric3's suggested intro: drop the CSS acronym and the span-label tuple in favor of a plainer sentence, and state the MetricWriter destinations (msgpack to the Datadog Agent, OTLP to the configured OTLP endpoint) up front. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace the single-producer/aggregator sketch with bric3's suggested diagram: show the MPSC inbox as the boundary -- app/producer threads enqueue SpanSnapshots, control threads enqueue SignalItems -- and the aggregator thread as the sole owner handling both, enumerating the Report/Clear/Stop signals. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

dougqh added comp: metrics Metrics tag: ai generated Largely based on code generated by an AI or LLM tag: no release notes Changes to exclude from release notes type: documentation labels Jul 27, 2026

dougqh requested a review from bric3 July 27, 2026 16:49

dougqh marked this pull request as ready for review July 27, 2026 16:53

dougqh requested a review from a team as a code owner July 27, 2026 16:53

dougqh requested a review from ygree July 27, 2026 16:53

datadog-datadog-prod-us1-2 Bot reviewed Jul 27, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Base automatically changed from dougqh/metrics-arbitrary-tags to master July 27, 2026 21:06

gh-worker-dd-mergequeue-cf854d Bot requested a review from a team as a code owner July 27, 2026 21:06

dougqh force-pushed the dougqh/css-package-doc branch from 50cecf3 to 1f7848c Compare July 28, 2026 13:13

bric3 reviewed Jul 28, 2026

View reviewed changes

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Comment thread dd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

dougqh and others added 2 commits July 28, 2026 13:33

dougqh changed the title ~~Document the client-side-stats package design (package-info)~~ Document the design in package-info (client-side stats) Jul 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Document the design in package-info (client-side stats) - #12082

Document the design in package-info (client-side stats)#12082
dougqh wants to merge 4 commits into
masterfrom
dougqh/css-package-doc

dougqh commented Jul 27, 2026 •

edited

Loading

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jul 27, 2026 •

edited by datadog-official Bot

Loading

Uh oh!

datadog-datadog-prod-us1-2 Bot left a comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-sts Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

dougqh commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contents

Stacking

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jul 27, 2026 • edited by datadog-official Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

datadog-datadog-prod-us1-2 Bot left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-sts Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dougqh commented Jul 27, 2026 •

edited

Loading

datadog-datadog-prod-us1-2 Bot commented Jul 27, 2026 •

edited by datadog-official Bot

Loading

dd-octo-sts Bot commented Jul 28, 2026 •

edited

Loading